Перейти к основному содержимому

Документация проекта и кода

· 4 мин. чтения

Документирование - финальный этап процесса разработки. Если хочется общей картины, то вот как это выглядит в типичном случае:

  1. Заказ. Клиент заказывает проект, незная примерно чего он хочет.
  2. Предложение. Компания хвалится что уже делала много подобных проектов и спрашивает детали и плавно переходит к заключению договора.
  3. Разработка
    1. Анализ - много беседы с клиентом что-бы понять его ситуацию и его нужды. Результат анализа - техническая спецификация, т.е. минимальные требования которым должен соответствовать продукт
    2. Дизайн - проектирование на высоком уровне БД и оценка необходимых задач
    3. Реализация
    4. Конечное тестирование
    5. Документирование
  4. Поддержка (Support)
  5. Оценка квалитета

Цель спецификации — определение требуемых (must), желательных  (should), и низкоприоритетных (could/would) функциональных требований в минимальных нефункциональных условиях.

Цель документации в предоставлении детальной информации о конечном продукте/системе. Если в анализе рассматривались абстрактные пользователи, процессы, связи, то в документации всё чётко.

Возможности пользователя​

Ключевые слова для этой документации - use cases и user's manual. В use'case-ах описываются действия пользователя и маршруты как реагирует система. В user's manual описываются те же возможности пользователя, но как правило с более графическими возможностями и с меньшим количеством технических деталей

Автоматическое документирование кода​

Если wiki ещё может быть полезным программистам, то Office Word - наврядли. Всё дело в неудобном оглавлении, необходимости кроссылочности и связями с кодом. Поэтому для документирования кода используют программы-генераторы, сканирующие файлы проекта в поиске комментариев. Если же комментариев нет, а как работает система вы не знаете то прийдётся заняться неприятной работой reverse-engineering'а.

Многие IDE (Zend, Visual Studio, Netbeans) уже включают в себя средства документирования, но никакого общего стандарта до сих пор нет. В своём большинстве, цель генераторов - составить нечто типа энциклопедии всех функций, классов, объектов, иерархий классов, связей между файлами, используемые компоненты и третьи программные продукты. Вся эта огромная информация редко когда может быть полезна начинающему программисту, которому в действительности сначала нужны UML схемы общей архитектуры:

  • Логические разделы или то что видет пользователь (use case, интерфейс, цель инфосистемы)
  • Общий вид потока информации (связь с БД, темплейты, сервисы, глобальные объекты)
  • Соответсвие логическим разделам физическим файлам и таблицам БД (модульность платформы)

Генераторы можно условно разделить на:

Генераторы как правило по-своему хранят данные и комментарии, завися от языка, однако последние тенденции например в Visual Studio показывают популяризацию xml. DocBook - одна их предлагаемых универсальных схем.

Внутренняя документация (Developer's guide)​

Обычно делается в wiki/confluence и включает в себя

  • Концептуальный обзор — какие сущности и какие связи используются (Concept diagram, DB schema)
  • Согласованный стандарт кода для проекта, т.е. какой синтаксис используется для разных типов кода (PHP, Javascript, SQL, RegExp..)
  • Архитектурный обзор — какое ПО используется на сервере, как управляются серверы, как обновляются, какие среды для разработки существуют
  • Как развернуть приложение у себя (installation guide)
  • Какой workflow для разработки одной задачи — что надо менять/отмечать в issue tracker'е, как писать миграции
  • Диаграмма классов (Class diagram) — на случай если часть кода (библиотека) достаточно сложная, то имеет смысл методы и свойства нарисовать в контексте этого набора

Документирование внешних API​

Cвязано с автоматическим документированием кода - передаваемые параметры хочется напрямую получать из кода и соответсвующих контроллеров, что-бы не происходило рассинхронизации кода от документации. Но нужен и guide для разработчиков с библиотеками и/или примерами использования этого API

Roadmap​

Я предпочитаю выделять и группировать задачи в виде mind map - это позволяет визуально выделить (размером шрифта), большие и кластерные задачи.

Читайте также: